JBoss.orgCommunity Documentation
The Transaction Capabilities Application Part (TCAP) is defined in ITU-T Recommendations Q.771-Q.775. TCAP allows services at network nodes to communicate with each other using an agreed-upon set of data elements. Its primary purpose is to facilitate multiple concurrent dialogs between the same sub-systems on the same machines, using Transaction IDs to differentiate these, similar to the way TCP ports facilitate multiplexing connections between the same IP addresses on the Internet.
The org.mobicents.protocols.ss7.tcap.api.TCAPStack
interface defines the methods required to represent TCAP
Protocol Stack. TCAPStack exposes org.mobicents.protocols.ss7.tcap.api.TCAPProvider
that interacts directly
with TCAPStack. TCAPProvider defines methods that will be used by TCAP User Part to create new
org.mobicents.protocols.ss7.tcap.api.tc.dialog.Dialog
to be sent across network.
TCAP User Part also allows to registerorg.mobicents.protocols.ss7.tcap.api.TCListener
to listen TCAP messages.
TCAPProvider also exposes org.mobicents.protocols.ss7.tcap.api.DialogPrimitiveFactory
to create dialog primitives
and org.mobicents.protocols.ss7.tcap.api.ComponentPrimitiveFactory
to create components.
Components are a means of invoking an operation at a remote node
The UML Class Diagram looks like
The org.mobicents.protocols.ss7.tcap.TCAPStackImpl
is concrete implementation of TCAPStack
.
The TCAP User Part creates instance of TCAPStackImpl
passing the reference of SccpProvider
and
new instance of SccpAddress
representing address to which bind listener. The TCAP
stack creates internaly Mobicents MAP
Stack implementation.
Passed SccpAddress
is used to match against incoming messages destination address.
SccpProvider sccpProvider = getSccpProvider(); //JNDI lookup of SCCP Stack and get Provider
SccpAddress localAddress createLocalAddress();
TCAPStack tcapStack = new TCAPStackImpl(sccpPprovider, localAddress);
...
private SccpAddress createLocalAddress()
{
return new SccpAddress(RoutingIndicator.ROUTING_BASED_ON_DPC_AND_SSN, 1, null, 8);
}
The reference to SccpProvider
is received from SccpStack
.
To get handle to SccpStack
do the JNDI look-up passing the
JNDI name configured in SS7 service as explained in Section 6.3, “Access Point”
The TCAP User Part should register the concrete implementation of
TCListener
with TCAPProvider
to listen for incoming TCAP messages.
public class Client implements TCListener{
.....
tcapProvider = tcapStack.getProvider();
tcapProvider.addTCListener(this);
....
}
The TCAP User Part leverages TCAPProvider to create new Dialog. The component's between the nodes are exchanged within this Dialog
clientDialog = this.tcapProvider.getNewDialog(thisAddress, remoteAddress);
The TCAP User Part leverages ComponentPrimitiveFactory to create new components. These components are sent usig the dialog
//create some INVOKE
Invoke invoke = cpFactory.createTCInvokeRequest();
invoke.setInvokeId(this.clientDialog.getNewInvokeId());
OperationCode oc = cpFactory.createOperationCode();
oc.setLocalOperationCode(12L);
invoke.setOperationCode(oc);
//no parameter
this.clientDialog.sendComponent(invoke);
Below is TCAP User Part example. This example creates dialog and exchanges messages withing structured dialog. Refer to source for function calls:
public class Client implements TCListener{
//encoded Application Context Name
public static final long[] _ACN_ = new long[] { 0, 4, 0, 0, 1, 0, 19, 2 };
private TCAPStack stack;
private SccpAddress thisAddress;
private SccpAddress remoteAddress;
private TCAPProvider tcapProvider;
private Dialog clientDialog;
Client(SccpProvider sccpPprovider, SccpAddress thisAddress,SccpAddress remoteAddress) {
super();
this.stack = new TCAPStackImpl(sccpPprovider,thisAddress); //pass address, so stack can register in SCCP
this.runningTestCase = runningTestCase;
this.thisAddress = thisAddress;
this.remoteAddress = remoteAddress;
this.tcapProvider = this.stack.getProvider();
this.tcapProvider.addTCListener(this);
}
private static SccpProvider getSccpProvider() throws NamingException {
// no arg is ok, if we run in JBoss
InitialContext ctx = new InitialContext();
try {
String providerJndiName = "/mobicents/ss7/sccp";
return ((SccpStack) ctx.lookup(providerJndiName)).getSccpProvider();
} finally {
ctx.close();
}
}
public void start() throws TCAPException, TCAPSendException {
clientDialog = this.tcapProvider.getNewDialog(thisAddress, remoteAddress);
ComponentPrimitiveFactory cpFactory = this.tcapProvider.getComponentPrimitiveFactory();
//create some INVOKE
Invoke invoke = cpFactory.createTCInvokeRequest();
invoke.setInvokeId(this.clientDialog.getNewInvokeId());
OperationCode oc = cpFactory.createOperationCode();
oc.setLocalOperationCode(12L);
invoke.setOperationCode(oc);
//no parameter
this.clientDialog.sendComponent(invoke);
ApplicationContextName acn = this.tcapProvider.getDialogPrimitiveFactory()
.createApplicationContextName(_ACN_);
//UI is optional!
TCBeginRequest tcbr = this.tcapProvider.getDialogPrimitiveFactory().createBegin(this.clientDialog);
tcbr.setApplicationContextName(acn);
this.clientDialog.send(tcbr);
}
public void onDialogReleased(Dialog d)
{
d.keepAlive();
}
public void onInvokeTimeout(Invoke tcInvokeRequest)
{
}
public void onDialogTimeout(Dialog d)
{
}
public void onTCBegin(TCBeginIndication ind) {
}
public void onTCContinue(TCContinueIndication ind) {
//send end
TCEndRequest end = this.tcapProvider.getDialogPrimitiveFactory().createEnd(ind.getDialog());
end.setTermination(TerminationType.Basic);
try {
ind.getDialog().send(end);
} catch (TCAPSendException e) {
throw new RuntimeException(e);
}
}
public void onTCEnd(TCEndIndication ind) {
//should not happen, in this scenario, we send data.
}
public void onTCUni(TCUniIndication ind) {
//not going to happen
}
public void onTCPAbort(TCPAbortIndication ind) {
// TODO Auto-generated method stub
}
public void onTCUserAbort(TCUserAbortIndication ind) {
// TODO Auto-generated method stub
}
public static void main(String[] args)
{
SccpAddress localAddress = new SccpAddress(RoutingIndicator.ROUTING_BASED_ON_DPC_AND_SSN, 1, null, 8);
SccpAddress remoteAddress = new SccpAddress(RoutingIndicator.ROUTING_BASED_ON_DPC_AND_SSN, 2, null, 8);
Client c = new Client(getSccpProvider(),localAddress,remoteAddress);
}
}